Overview

Melodee uses DecentDB for local, generated search databases. These files are separate from the primary Melodee PostgreSQL database and can be rebuilt from source data when necessary.

DecentDB is currently used for:

  • MusicBrainz search data: the local MusicBrainz artist, alias, relation, and album lookup database.
  • Artist search cache: the local artist search repository used to speed up artist matching and enrichment.

Melodee does not store user accounts, playlists, play history, ratings, or library metadata in these DecentDB files. Those records live in the primary PostgreSQL database.

Configuration

The DecentDB databases are configured with these connection strings:

Connection string Purpose
MusicBrainzConnection Local MusicBrainz lookup database
ArtistSearchEngineConnection Local artist search cache database

In container deployments, the same values can be supplied with environment variables:

ConnectionStrings__MusicBrainzConnection="Data Source=/app/storage/_search-engines/musicbrainz/musicbrainz.ddb"
ConnectionStrings__ArtistSearchEngineConnection="Data Source=/app/storage/_search-engines/artistSearchEngine.ddb"

Use your configured paths as the source of truth. Older installations may use .db filenames while newer examples use .ddb; the connection string path is what matters.

Doctor Compatibility Checks

Doctor opens both DecentDB files with the current Melodee DecentDB provider. If the file was created by a newer or incompatible DecentDB engine, Doctor reports an issue similar to:

MusicBrainz DecentDB database uses a file format that is not supported by the current DecentDB provider.
Provider error: unsupported DecentDB file format version 11

This is DecentDB error 8 (ERR_UNSUPPORTED_FORMAT_VERSION). It means the current Melodee process cannot safely read that generated search database. Search and enrichment may continue in degraded mode, but the affected database must be upgraded with decentdb-migrate or rebuilt before it can be used.

Migration Strategy

Use DecentDB’s standalone decentdb-migrate utility first. The utility reads the old database and writes an upgraded copy to a new path; it does not overwrite the source database in place.

Use this order:

  1. Note the DecentDB version shown in Melodee’s migration dialog.
  2. Download and extract the matching archive from the DecentDB releases page. Release archives include decentdb-migrate and the decentdb CLI.
  3. Stop every Melodee instance that can access the affected file.
  4. Run decentdb-migrate with the configured database path as --source and a new, nonexistent path as --dest.
  5. Verify the new file with the decentdb executable from the same release.
  6. Preserve the original database and its sidecars, then promote the migrated database to the configured path.
  7. Restart Melodee and confirm the DecentDB checks pass in Admin > Doctor.

See DecentDB’s official migration guide for the tool’s supported source formats and build-from-source alternative.

Migration Example

The web migration dialog generates these commands with the active configured path. A MusicBrainz migration follows this shape:

./decentdb-migrate \
  --source /path/to/musicbrainz.ddb \
  --dest /path/to/musicbrainz_migrated.ddb

Do not continue until the utility reports:

Migration complete! Your upgraded database is ready at: /path/to/musicbrainz_migrated.ddb

Verify the upgraded copy with the CLI from the same release:

./decentdb info --db /path/to/musicbrainz_migrated.ddb

Keep Melodee stopped while replacing the active file. Preserve the original .ddb file and any .wal, .coord, or .wal-idx sidecars until normal operation is verified. If Melodee runs in a container, translate the displayed container path to the corresponding host volume path when running the utility on the host.

If the migration utility reports that the source format has no supported migration path, use the rebuild procedure below.

Backup Before Rebuild

Back up the main database and generated DecentDB files before changing anything. The example below preserves common DecentDB companion file names.

#!/usr/bin/env bash
set -euo pipefail

backup_root="$HOME/melodee-decentdb-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup_root"

musicbrainz_db="/path/to/search-engine-storage/musicbrainz/musicbrainz.ddb"
artist_search_db="/path/to/search-engine-storage/artistSearchEngine.ddb"

backup_decentdb_file() {
  local db_path="$1"
  local db_name
  db_name="$(basename "$db_path")"

  for suffix in "" ".wal" ".coord" ".wal-idx" "-wal" ".shm" "-shm"; do
    if [ -f "${db_path}${suffix}" ]; then
      cp -a "${db_path}${suffix}" "$backup_root/${db_name}${suffix}"
    fi
  done
}

backup_decentdb_file "$musicbrainz_db"
backup_decentdb_file "$artist_search_db"

echo "Backed up DecentDB files to $backup_root"

Also back up PostgreSQL before a Melodee upgrade. See Backup & Recovery for full backup guidance.

Example: Rebuild Incompatible DecentDB Files

This example renames incompatible generated DecentDB files so Melodee can create fresh files with the current provider.

#!/usr/bin/env bash
set -euo pipefail

stamp="$(date +%Y%m%d-%H%M%S)"

musicbrainz_db="/path/to/search-engine-storage/musicbrainz/musicbrainz.ddb"
artist_search_db="/path/to/search-engine-storage/artistSearchEngine.ddb"

move_decentdb_file_aside() {
  local db_path="$1"

  for suffix in "" ".wal" ".coord" ".wal-idx" "-wal" ".shm" "-shm"; do
    if [ -f "${db_path}${suffix}" ]; then
      mv "${db_path}${suffix}" "${db_path}${suffix}.unsupported-$stamp"
    fi
  done
}

# Stop Melodee before moving active database files.
# podman compose down
# docker compose down

move_decentdb_file_aside "$musicbrainz_db"
move_decentdb_file_aside "$artist_search_db"

# Start Melodee again.
# podman compose up -d
# docker compose up -d

After the files are moved aside, rebuild the generated databases.

MusicBrainz

Use one of these options:

  • In the web UI, go to Admin > Doctor and use Generate MusicBrainz Database.
  • In the web UI, go to Admin > Jobs and run MusicBrainzUpdateDatabaseJob.
  • From the CLI, run:
./mcli job musicbrainz-update

MusicBrainz rebuilds can take a long time because Melodee downloads and imports the MusicBrainz dump into a local DecentDB file.

Artist Search Cache

Use one of these options:

  • In the web UI, go to Admin > Jobs and run ArtistSearchEngineRepositoryHousekeepingJob.
  • From the CLI, run:
./mcli job artistsearchengine-refresh

The artist search cache is generated from Melodee’s library data and configured artist search providers. It can be rebuilt after the incompatible file is moved aside.

Verify The Migration

Run Doctor after upgrading or rebuilding:

./mcli doctor --verbose

Or open Admin > Doctor in the web UI.

The following checks should pass:

  • MusicBrainzDatabase
  • ArtistSearchEngineDatabase

If Doctor still reports an unsupported DecentDB file format, confirm that:

  • Melodee is running the version you expect.
  • The active connection strings point to the rebuilt files.
  • No stale .wal, .coord, .wal-idx, -wal, .shm, or -shm companion files remain beside the active database.
  • The app container or service was restarted after the rebuild.

What Not To Delete

Do not delete the primary PostgreSQL database when resolving DecentDB search cache compatibility issues. The unsupported DecentDB file-format warning applies to generated local search databases, not the primary Melodee database.